"""
统一响应格式工具 - 定义标准化的API响应格式

响应格式设计原则：
1. 统一的数据结构，便于前端处理
2. 明确的状态码，便于错误处理
3. 清晰的消息描述，便于调试和用户提示
4. 可选的数据字段，适应不同接口需求
"""

# 从typing导入Dict和Any，用于类型提示
# Dict表示字典类型，Any表示任意类型
from typing import Dict, Any


def success_response(data: Any = None, msg: str = "success", code: int = 200) -> Dict[str, Any]:
    """
    构造成功的响应
    
    响应格式规范：
    {
        "code": 200,           # 状态码，200表示成功
        "msg": "success",      # 消息描述，表示操作成功
        "data": {...}          # 实际数据，可为任意类型
    }
    
    参数:
        data: 响应数据，可选
              可以是字典、列表、字符串等任意类型的数据
        msg: 响应消息，默认为"success"
              用于描述操作结果的文字说明
        code: 响应状态码，默认为200
              HTTP状态码，200表示成功
        
    返回:
        标准化的成功响应字典
              格式统一，便于前端解析和处理
    """
    # 构造并返回标准化的成功响应
    # 采用固定的数据结构确保接口响应的一致性
    return {
        "code": code,    # 状态码，标识响应状态
        "msg": msg,      # 消息，描述操作结果
        "data": data     # 数据，包含接口返回的实际内容
    }


def error_response(msg: str = "error", code: int = 500, data: Any = None) -> Dict[str, Any]:
    """
    构造错误的响应
    
    错误响应格式规范：
    {
        "code": 500,           # 状态码，500表示服务器内部错误
        "msg": "error",        # 错误消息，描述错误原因
        "data": {...}          # 错误相关数据，可选
    }
    
    参数:
        msg: 错误消息，默认为"error"
              描述错误原因的文字说明
        code: 错误状态码，默认为500
              HTTP状态码，500表示服务器内部错误
        data: 错误数据，可选
              与错误相关的附加信息
        
    返回:
        标准化的错误响应字典
              格式统一，便于前端处理错误情况
    """
    # 构造并返回标准化的错误响应
    # 与成功响应保持一致的数据结构，便于统一处理
    return {
        "code": code,    # 状态码，标识错误类型
        "msg": msg,      # 错误消息，描述错误原因
        "data": data     # 错误数据，包含错误相关的附加信息
    }